home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995…tember: Reference Library / Dev.CD Sep 95 RL / Dev.CD Sep 95 RL.toast / mac / Technical Documentation / develop / develop Issue 22 code / PCI Driver Sample / NCR_DriverProject / Src / NCRDriver.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-04-05  |  8.0 KB  |  209 lines  |  [TEXT/MPCC]
  1. /*                                        NCRDriver.h                                    */
  2. /*
  3.  * NCRDriver.h
  4.  * Copyright © 1994 Apple Computer Inc. All rights reserved.
  5.  */
  6. /*    .___________________________________________________________________________________.
  7.       | This is the public interface to the sample driver. This file should be included    |
  8.     | in application programs that use the driver. (The test program includes the        |
  9.     | private headers for debugging).                                                    |
  10.     |                                                                                    |
  11.     | NCRDriver is a sample device driver for a PCI interface card. It supports the        |
  12.     | NCR 8250 interface card and the NCR 53C825 SCSI bus interface chip. This driver    |
  13.     | was written to illustrate PCI device driver programming, and should not be taken    |
  14.     | as an example, either of a production driver (it is too inefficient) or of a SCSI    |
  15.     | device driver.                                                                    |
  16.     .___________________________________________________________________________________.
  17.  */
  18. /*
  19.  * The following PBControl requests are unique to the PCI Sample Driver:
  20.  *
  21.  *    kControlDoSCSIBusReset        Reset the SCSI bus. csParam values are ignored.
  22.  *    kControlGetOrSetInitiatorID    Access the Initiator ID. csParam[0] has the new ID or
  23.  *                                gets the current ID.
  24.  * To execute a SCSI Command, an application provides SCSI-specific parameters in
  25.  * a NCRSCSIParam record, stores the address of this record in the ioMisc field of
  26.  * IOParam record, provides the user buffer address and transfer length, and executes
  27.  * PBRead or PBWrite. For example,
  28.  *        myNCRParam.driverAction            = kNCRDriverInputAllowed;
  29.  *        myNCRParam.targetID                = <SCSI Bus ID>;
  30.  *        myNCRParam.logicalUnitNumber    = 0;
  31.  *        myNCRParam.scsiCommand[0..11]    = <SCSI command bytes>;
  32.  *        myNCRParam.scsiCommandLength    = <length of SCSI Command>;
  33.  *        myNCRParam.watchdogTimeout        = <timeout in MSec>
  34.  *
  35.  *        myIOPB.ioRefNum                    = <NCR Driver RefNum from OpenDriver>;
  36.  *        myIOPB.ioVersNum                = <ignored, use zero>;
  37.  *        myIOPB.ioPermissn                = <ignored, use zero>;
  38.  *        myIOPB.ioMisc                    = (Ptr) &myNCRParam;
  39.  *        myIOPB.ioBuffer                    = <data buffer, NULL if none>;
  40.  *        myIOPB.ioReqCount                = <transfer count, zero if none>;
  41.  *        myIOPB.ioActCount                = <will be set by the I/O request>;
  42.  *        myIOPB.ioPosMode                = ioMapBuffer; <Note: currently undefined>
  43.  *        myIOPB.ioPosOffset                = <ignored, use zero>;
  44.  *
  45.  * The driver returns status codes defined in <scsi.h>
  46.  */
  47. #ifndef __NCRSCSIDriver__
  48. #define __NCRSCSIDriver_
  49. #include <Types.h>
  50. #include <OSUtils.h>
  51. #include <Files.h>
  52.  
  53. #define kDriverNamePString        "\p.NCRSCSIDriver"    /* Driver name: Pascal string    */
  54. #define kDriverNameCString        ".NCRSCSIDriver"    /* Driver name: C string        */
  55.  
  56. #ifndef REZ
  57. /*
  58.  * Public PBControl codes we can't find in the headers.
  59.  */
  60. enum {
  61.     driverPowerLow                = 47,
  62.     driverPowerHigh                = 48
  63. };
  64. /*
  65.  * NCR SCSI Driver private PBControl and PBStatus csCodes.
  66.  */
  67. enum {
  68.     kControlDoSCSIBusReset        = 1024,    /* PBControl, no csCode fields set            */
  69.     kControlGetOrSetInitiatorID,        /* NCRDriverInitiatorIDParam                */
  70.     kControlDoSCSIRundown                /* Attempt to stabalize the SCSI bus        */ 
  71. };
  72.  
  73. #define kNoSCSITimeout            0        /* For watchdogTimeout parameter            */
  74.  
  75. /*
  76.  * Values for the driverAction parameter for the PBRead/PBWrite NCRSCSIParam command.
  77.  * Note: the NCR script relies on these particular values.
  78.  */
  79. enum {
  80.     kNCRDriverNoDataPhase = 0,            /* PBRead, TestUnitReady or similar            */
  81.     kNCRDriverInputAllowed = 1,            /* PBRead, RequestSense, Read, or similar    */
  82.     kNCRDriverOutputAllowed = 2,        /* PBWrite, Write, Mode Select, or similar    */
  83.     kNCRDriverActionMask = 0x07            /* Allowance bits                            */
  84. };
  85.  
  86. #define kNCRMemoryTestBusID        (65535)
  87.  
  88. /*
  89.  * This is passed in the ioMisc field of a PBRead or PBWrite command.
  90.  * Note the following:
  91.  *    IOParam.ioMisc        Address of the NCRSCSIParam record.
  92.  *  IOParam.ioBuffer    User data buffer (must not be NULL)
  93.  *    IOParam.ioReqCount    User data count (must not be zero)
  94.  *    IOParam.ioActCount    Actual data transfer
  95.  *    IOParam.ioPosMode    Ignored
  96.  *    IOParam.ioPosOffset    Ignored
  97.  *    driverAction        Must correspond to PBRead or PBWrite. If the request does not
  98.  *                        require a data phase (Test Unit Ready, for example), you must
  99.  *                        provide a data buffer and a non-zero transfer count: this is
  100.  *                        required by the Device Manager.
  101.  *    stateTag            A longword passed to the LogState macro.
  102.  *
  103.  * The caller must supply a non-null ioBuffer and non-zero ioReqCount -- this is a
  104.  * limitation of the Device Manager. The driver uses the driverAction parameter to
  105.  * determine whether an I/O buffer is needed, and ignores the caller's parameters
  106.  * if driverAction equals kNCRDriverNoDataPhase.
  107.  *
  108.  * If the targetID == kNCRMemoryTestBusID the driver runs a test script that does not
  109.  * access remote SCSI devices. Two tests may be run:
  110.  *    memory move test        Copy data between the IOParam.ioBuffer and a buffer
  111.  *                            defined by memTestPhysAddress (which must be non-NULL).
  112.  *                            ioReqCount bytes will be copied. (PBRead copies from
  113.  *                            the memTestPhysAddress, PBWrite copies to it.). The
  114.  *                            transfer burst length is in memTestBurstLength. Use one
  115.  *                            of the values in NCR53C825.h.
  116.  *    interrupt test            Perform a minimal NCR script that does nothing. For this
  117.  *                            test, memTestPhysAddress must be NULL. The caller must
  118.  *                            provide a dummy ioBuffer and non-zero ioReqCount.
  119.  *
  120.  * The buffer in memTestPhysAddress is computed using LockMemoryContiguous and
  121.  * GetPhysical. It must be resident, locked, and physically contiguous.
  122.  *
  123.  * TBS: The caller can request an immediate interrupt test by (PBControl ...)
  124.  *
  125.  */
  126. #if STRUCTALIGNMENTSUPPORTED
  127. #pragma options align=power
  128. #endif
  129. struct NCRSCSIParam {
  130.     unsigned short        driverAction;            /* -> Operation required            */
  131.     unsigned short        targetID;                /* -> SCSI Bus ID                    */
  132.     unsigned short        logicalUnitNumber;        /* -> SCSI LUN -- not supported yet    */
  133.     unsigned char        scsiCommand[12];        /* -> SCSI Command itself            */
  134.     unsigned short        scsiCommandLength;        /* -> 0, 6, 10, or 12 bytes            */
  135.     Duration            watchdogTimeout;        /* -> Msec timeout, zero = none        */
  136.     unsigned char        statusByte;                /* <- Command status                */
  137.     unsigned char        messageByte;            /* <- Command Complete message        */
  138.     UInt32                stateTag;                /* -> Tag word for testing            */
  139.     PhysicalAddress        memTestPhysAddress;        /* <> Buffer for memory move test    */
  140.     UInt32                memTestBurstLength;        /* -> Memory test configuration        */
  141. };
  142. #if STRUCTALIGNMENTSUPPORTED
  143. #pragma options align=reset
  144. #endif
  145. typedef struct NCRSCSIParam NCRSCSIParam, *NCRSCSIParamPtr;
  146.  
  147. /*
  148.  * NCRDriverInitiatorIDParam lets the caller get and set the initiator bus ID
  149.  * stored in non-volatile memory (NVRAM).
  150.  *
  151.  * PBStatus, csCode = kControlGetOrSetInitiatorID retrieves the current value.
  152.  * PBControl, csCode = kControlGetOrSetInitiatorID stores a new value.
  153.  */
  154. #if defined(powerc) || defined (__powerc)
  155. #pragma options align=mac68k
  156. #endif
  157. struct NCRDriverInitiatorIDParam {
  158.     QElemPtr            qLink;
  159.     short                qType;
  160.     short                ioTrap;
  161.     Ptr                    ioCmdAddr;
  162.     IOCompletionUPP        ioCompletion;
  163.     OSErr                ioResult;
  164.     StringPtr            ioNamePtr;
  165.     short                ioVRefNum;
  166.     short                ioCRefNum;
  167.     short                csCode;
  168.     unsigned short        initiatorID;            /*  The initiator SCSI bus ID            */
  169. };
  170. #if defined(powerc) || defined(__powerc)
  171. #pragma options align=reset
  172. #endif
  173. typedef struct NCRDriverInitiatorIDParam NCRDriverInitiatorIDParam;
  174. typedef NCRDriverInitiatorIDParam *NCRDriverInitiatorIDParamPtr;
  175.  
  176. /*
  177.  * NCRDriverRundownParam is intended to be called after a device timeout.
  178.  * It attempts to bring the bus to a stable state.
  179.  *
  180.  * If the bus is not busy (or we are not the initiator), it does nothing.
  181.  * Otherwise it runs the "failure" script.
  182.  *
  183.  */
  184. #if defined(powerc) || defined (__powerc)
  185. #pragma options align=mac68k
  186. #endif
  187. struct NCRDriverRundownParam {
  188.     QElemPtr            qLink;
  189.     short                qType;
  190.     short                ioTrap;
  191.     Ptr                    ioCmdAddr;
  192.     IOCompletionUPP        ioCompletion;
  193.     OSErr                ioResult;
  194.     StringPtr            ioNamePtr;
  195.     short                ioVRefNum;
  196.     short                ioCRefNum;
  197.     short                csCode;
  198.     Duration            watchdogTimeout;        /* -> Msec timeout, zero = none        */
  199. };
  200. #if defined(powerc) || defined(__powerc)
  201. #pragma options align=reset
  202. #endif
  203. typedef struct NCRDriverRundownParam NCRDriverRundownParam;
  204. typedef NCRDriverRundownParam *NCRDriverRundownParamPtr;
  205.  
  206. #endif /* Not REZ */
  207. #endif /* __NCRDriver__ */
  208.  
  209.